gtkbuilder.sgml
gtkhbox.sgml
gtkmessagedialog.sgml
+gtkobject.sgml
gtkorientable.sgml
gtkpagesetupunixdialog.sgml
gtkseparator.sgml
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GtkObject
-
-<!-- ##### SECTION Short_Description ##### -->
-The base class of the GTK+ type hierarchy
-
-<!-- ##### SECTION Long_Description ##### -->
-<refsect2>
-<title>Description</title>
-<para>
-#GtkObject is the base class for all widgets, and for a few
-non-widget objects such as #GtkAdjustment. #GtkObject predates
-#GObject; non-widgets that derive from #GtkObject rather than
-#GObject do so for backward compatibility reasons.
-</para>
-<para>
-#GtkObject<!-- -->s are created with a "floating" reference count.
-This means that the initial reference is not owned by anyone. Calling
-g_object_unref() on a newly-created #GtkObject is incorrect, the floating
-reference has to be removed first. This can be done by anyone at any time,
-by calling g_object_ref_sink() to convert the floating reference into a
-regular reference. g_object_ref_sink() returns a new reference if an object
-is already sunk (has no floating reference).
-</para>
-<para>
-When you add a widget to its parent container, the parent container
-will do this:
-<informalexample><programlisting>
- g_object_ref_sink (G_OBJECT (child_widget));
-</programlisting></informalexample>
-This means that the container now owns a reference to the child widget
-and the child widget has no floating reference.
-</para>
-<para>
-The purpose of the floating reference is to keep the child widget alive
-until you add it to a parent container:
-<informalexample><programlisting>
- button = gtk_button_new (<!-- -->);
- /* button has one floating reference to keep it alive */
- gtk_container_add (GTK_CONTAINER (container), button);
- /* button has one non-floating reference owned by the container */
-</programlisting></informalexample>
-</para>
-<para>
-#GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
-That is, after calling gtk_window_new(), the #GtkWindow will have one
-reference which is owned by GTK+, and no floating references.
-</para>
-
-<para>
-One more factor comes into play: the "destroy" signal, emitted by the
-gtk_object_destroy() method. The "destroy" signal asks all code owning a
-reference to an object to release said reference. So, for example, if you call
-gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
-it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
-be removed from its parent container and the parent container will release its
-reference to the button. Because these references are released, calling
-gtk_object_destroy() should result in freeing all memory associated with an
-object, unless some buggy code fails to release its references in response to
-the "destroy" signal. Freeing memory (referred to as
-<firstterm>finalization</firstterm> only happens if the reference count reaches
-zero.
-</para>
-
-<para>
-Some simple rules for handling #GtkObject:
-<itemizedlist>
-<listitem><para>
-Never call g_object_unref() unless you have previously called g_object_ref(),
-even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
-true for #GObject; for #GObject, the creator of the object owns a reference.)
-</para></listitem>
-<listitem><para>
-Call gtk_object_destroy() to get rid of most objects in most cases.
-In particular, widgets are almost always destroyed in this way.
-</para></listitem>
-<listitem><para> Because of the floating reference count, you don't need to
-worry about reference counting for widgets and toplevel windows, unless you
-explicitly call g_object_ref() yourself.</para></listitem>
-</itemizedlist>
-</para>
-
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GObject
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkObject ##### -->
-<para>
-The object itself. You should never use these members directly -
- use the accessing macros instead.
-</para>
-
-
-<!-- ##### SIGNAL GtkObject::destroy ##### -->
-<para>
-Signals that all holders of a reference to the #GtkObject should release
-the reference that they hold. May result in finalization of the object
-if all references are released.
-</para>
-
-@object: the object which received the signal.
-
-
-<!-- ##### ENUM GtkObjectFlags ##### -->
-<para>
-Tells about the state of the object.
-</para>
-
-@GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
- internally by GTK+ to prevent reinvokations during destruction.
-@GTK_RESERVED_1:
-@GTK_RESERVED_2: reserved for future use
-
-<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
-<para>
-Gets the #GtkObjectFlags for an object without directly
-accessing its members.
-</para>
-
-@obj: the object whose flags are returned.
-
-
-<!-- ##### FUNCTION gtk_object_destroy ##### -->
-<para>
-Emits the "destroy" signal notifying all reference holders that they should
-release the #GtkObject. See the overview documentation at the top of the
-page for more details.
-</para>
-<para>
-The memory for the object itself won't be deleted until
-its reference count actually drops to 0; gtk_object_destroy() merely asks
-reference holders to release their references, it does not free the object.
-</para>
-
-@object: the object to destroy.
-
-
#include "gtkalias.h"
+/**
+ * SECTION:gtkobject
+ * @Short_description: The base class of the GTK+ type hierarchy
+ * @Title: GtkObject
+ * @See_also:#GObject
+ *
+ * #GtkObject is the base class for all widgets, and for a few
+ * non-widget objects such as #GtkAdjustment. #GtkObject predates
+ * #GObject; non-widgets that derive from #GtkObject rather than
+ * #GObject do so for backward compatibility reasons.
+ *
+ * #GtkObject<!-- -->s are created with a "floating" reference count.
+ * This means that the initial reference is not owned by anyone. Calling
+ * g_object_unref() on a newly-created #GtkObject is incorrect, the floating
+ * reference has to be removed first. This can be done by anyone at any time,
+ * by calling g_object_ref_sink() to convert the floating reference into a
+ * regular reference. g_object_ref_sink() returns a new reference if an object
+ * is already sunk (has no floating reference).
+ *
+ * When you add a widget to its parent container, the parent container
+ * will do this:
+ * <informalexample><programlisting>
+ * g_object_ref_sink (G_OBJECT (child_widget));
+ * </programlisting></informalexample>
+ * This means that the container now owns a reference to the child widget
+ * and the child widget has no floating reference.
+ *
+ * The purpose of the floating reference is to keep the child widget alive
+ * until you add it to a parent container:
+ * <informalexample><programlisting>
+ * button = gtk_button_new (<!-- -->);
+ * /* button has one floating reference to keep it alive */
+ * gtk_container_add (GTK_CONTAINER (container), button);
+ * /* button has one non-floating reference owned by the container */
+ * </programlisting></informalexample>
+ *
+ * #GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
+ * That is, after calling gtk_window_new(), the #GtkWindow will have one
+ * reference which is owned by GTK+, and no floating references.
+ *
+ * One more factor comes into play: the #GtkObject::destroy signal, emitted by the
+ * gtk_object_destroy() method. The #GtkObject::destroy signal asks all code owning a
+ * reference to an object to release said reference. So, for example, if you call
+ * gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
+ * it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
+ * be removed from its parent container and the parent container will release its
+ * reference to the button. Because these references are released, calling
+ * gtk_object_destroy() should result in freeing all memory associated with an
+ * object, unless some buggy code fails to release its references in response to
+ * the #GtkObject::destroy signal. Freeing memory (referred to as
+ * <firstterm>finalization</firstterm>) only happens if the reference count reaches
+ * zero.
+ *
+ * Some simple rules for handling #GtkObject:
+ * <itemizedlist>
+ * <listitem><para>
+ * Never call g_object_unref() unless you have previously called g_object_ref(),
+ * even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
+ * true for #GObject; for #GObject, the creator of the object owns a reference.)
+ * </para></listitem>
+ * <listitem><para>
+ * Call gtk_object_destroy() to get rid of most objects in most cases.
+ * In particular, widgets are almost always destroyed in this way.
+ * </para></listitem>
+ * <listitem><para> Because of the floating reference count, you don't need to
+ * worry about reference counting for widgets and toplevel windows, unless you
+ * explicitly call g_object_ref() yourself.</para></listitem>
+ * </itemizedlist>
+ */
+
+
enum {
DESTROY,
LAST_SIGNAL
class->destroy = gtk_object_real_destroy;
+ /**
+ * GtkObject::destroy:
+ * @object: the object which received the signal.
+ *
+ * Signals that all holders of a reference to the #GtkObject should release
+ * the reference that they hold. May result in finalization of the object
+ * if all references are released.
+ */
object_signals[DESTROY] =
g_signal_new (I_("destroy"),
G_TYPE_FROM_CLASS (gobject_class),
* Functions to end a GtkObject's life time
*
********************************************/
+/**
+ * gtk_object_destroy:
+ * @object: the object to destroy.
+ *
+ * Emits the #GtkObject::destroy signal notifying all reference holders that they should
+ * release the #GtkObject. See the overview documentation at the top of the
+ * page for more details.
+ *
+ * The memory for the object itself won't be deleted until
+ * its reference count actually drops to 0; gtk_object_destroy() merely asks
+ * reference holders to release their references, it does not free the object.
+ */
void
gtk_object_destroy (GtkObject *object)
{
* is a kinda nasty break up, it does make the size of
* derived objects smaller.
*/
+/**
+ * GtkObjectFlags:
+ * @GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
+ * internally by GTK+ to prevent reinvokations during destruction.
+ * @GTK_RESERVED_1: reserved for future use
+ * @GTK_RESERVED_2: reserved for future use
+ *
+ * Tells about the state of the object.
+ */
typedef enum
{
GTK_IN_DESTRUCTION = 1 << 0, /* Used internally during dispose */
GTK_RESERVED_2 = 1 << 3
} GtkObjectFlags;
-/* Macros for extracting the object_flags from GtkObject.
+/**
+ * GTK_OBJECT_FLAGS:
+ * @obj: the object whose flags are returned.
+ *
+ * Gets the #GtkObjectFlags for an object without directly
+ * accessing its members.
*/
#define GTK_OBJECT_FLAGS(obj) (GTK_OBJECT (obj)->flags)
projects / gtk4.git / commitdiff